home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2003 #12 / Amiga Plus CD - 2003 - No. 12.iso / AmigaPlus / Tools / AmigaSystem / PowerIconsRelease / PowerIcons.readme < prev    next >
Text File  |  2003-11-26  |  19KB  |  425 lines
  1.  
  2. Short:    NEW! 32bit PNG icons on your Amiga !!! (68K and MorphOS)
  3. Uploader: uni-dea@jumpy.it (Elena - www.elena-fractals.it)
  4. Author:   uni-dea@jumpy.it (Elena - www.elena-fractals.it)
  5. Type:     util/wb
  6. Requires: AmigaOS 3.5/3.9, Hi/True Color Workbench
  7. Replaces: util/wb/PowerIcons.lha
  8. Version:  1.05
  9.  
  10.  
  11.  ALWAYS DOWNLOAD AN UP TO DATE VERSION OF POWERICONS AND OTHER SOFTWARE OF MINE AT:
  12.   <http://www.elena-fractals.it/software.php>
  13.  
  14.  
  15.  PROGRAM HISTORY
  16.  ----------------------------
  17.  
  18.  1.05 (21 Nov 03)
  19.   -Added BETTEROUTLINE option to improve text outline effect.
  20.   -Added SCROLLSPEEDUP option to optimize Workbench icon scrolling (thanks to
  21.    a Georg Steger's idea).
  22.   -In the case no default base type icon is found in ENV:Sys (drawer, tool,
  23.    project, etc.) no icon was returned. Fixed.
  24.   -Removed a subtle bug in the 68K version causing weird system slowdowns and
  25.    crashes (register A4 in GetIconRectangleNew() was erroneously trashed by the
  26.    code generator). Thanks to Tony Aksnes for the patient beta testing.
  27.   -Some new example icons added
  28.  
  29.  1.04 (30 Oct 03)
  30.   -"Virgin" icons associated with executable files were loaded as Projects rather
  31.    than Tools. Fixed.
  32.   -Fixed a very dangerous bug in PrepIcon() that could lead to serious crashes and
  33.    system instability loading single-image color icons via GetDiskObject(New)().
  34.   -Added a workaround for a bug in the original IconControl() function which could
  35.    lead to crashes in conjunction with some single-image icons.
  36.   -Sometimes using TextMode=1 the icon text was not completely erased leaving a
  37.    vertical line at the extreme left. Fixed.
  38.   -Improved DrawIconStateNew(). Icon and text alignment should be more precise now.
  39.   -PNG icons for drawers without proper drawer data were passed to WB as tool icons,
  40.    thus the associated drawer could not be opened. Fixed.
  41.   -The example PNG icons included couldn't be loaded into paint programs because they
  42.    still had a wrong crc (most of them was created and snapshotted under the old PI
  43.    1.0). They're OK now.
  44.   -I created and included PowerIconsLogo.jpg: now PI has its official logo :-)
  45.  
  46.  1.03 (25 Oct 2003)
  47.   -Loading very little PNG icons (16x16 or so) could cause decoding buffer overflow
  48.    with consequent system crashes. Fixed.
  49.  
  50.  1.02 (23 Oct 2003)
  51.   -Default icons got wrong size with icon.library < 45.10. Fixed.
  52.   -Improved Workbench dragging of PNG icons using a white rectangle. Please don't ask
  53.    me to improve it further since it's only a drawback for WB.
  54.   -Added SWAPTEXTCOLORS option
  55.   -Using GHOST=100 no additional calculation will be computed for default icons,
  56.    so people thinking that the ghosting effect slows down scrolling may try this
  57.    (even if I don't believe that)
  58.   -Fixed some dangerous alignment problems that could cause crashes under some
  59.    circumstances and problems with Amidock.
  60.   -Overall code improvement and optimizations. Scrolling might be a bit faster now.
  61.  
  62.  1.01 (20 Oct 2003)
  63.   -CRC for icon hunk is now computed when writing icons back. So now you can load
  64.    no more "virgin" icons in ImageFX or other paint programs where they previously
  65.    issued a "CRC error" requester. Please note that ImageFX PNG loader is broken,
  66.    however: even if you choose "YES" to load alpha channel, it will be lost.
  67.  
  68.  
  69.  WHAT'S POWERICONS ??
  70.  --------------------
  71.  
  72.   In short: PowerIcons is a patch allowing you to use PNG icons (24 bit with or
  73.   without alpha channel) on your Amiga in a totally transparent and OS-friendly
  74.   way!
  75.  
  76.   Also, it performs transparency for default icons (ala Ghosty) and true color
  77.   mapping of standard Amiga icons (they can now be displayed in full quality
  78.   with their real colors and without palette-based remapping)
  79.  
  80.  
  81.  LEGAL
  82.  -----
  83.  
  84.   PowerIcons if FREEWARE!
  85.   Pretending to make money from a community who's trying to survive like Amiga
  86.   community is simply SAD.
  87.   PowerIcons is Copyright © 2003 Elena Novaretti
  88.   Any commercial usage of this archive (whole or partially) is FORBIDDEN.
  89.   PowerIcons may not be distributed without this accompanying README file.
  90.  
  91.  
  92.  A BRIEF HISTORY
  93.  ---------------
  94.  
  95.   Since years one of my greatest dreams was having 24 bit icons with alpha-
  96.   channel transparency on my Workbench.
  97.   Ambient, the official MorphOS desktop, firstly introduced PNG (24bit+alpha)
  98.   icon support in the Amiga scenery.
  99.   I'm actually an happy user and developer under MorphOS on my beloved Pegasos
  100.   board, but sincerely cannot use Ambient yet since it lacks too many features
  101.   compared with Opus Magellan, Workbench 3.9 or any other modern desktop.
  102.   Also, Ambient handles PNG icons internally without using any standard
  103.   icon.library API, so other programs cannot benefit of them!
  104.   For now, the only very shiny thing of Ambient is just PNG icons support:
  105.   so, how to lose them ??
  106.  
  107.   In the past I wrote some patches to give Workbench icons a better look.
  108.   First of them was Ghosty (Aminet), allowing transparency for default icons.
  109.   Then I made an improved version called "Ghosty+", which I never released to
  110.   the public since it was a bit experimental, but which also allowed standard
  111.   Amiga color icons to be displayed with their own proper 256 colors (with no
  112.   remapping, so with an apparently "near-true color" quality - except for the
  113.   ugly border).
  114.   And next came PowerIcons. It has been a really hard job but at the end it
  115.   came out and it was really worth the trouble!
  116.  
  117.  
  118.  REQUIREMENTS
  119.  ------------
  120.  
  121.   All you need is AmigaOS 3.5 or 3.9 running an Hi/True Color Workbench,
  122.   no special library or extra file is required.
  123.   Please note that 8 bit screenmodes are NOT supported for obvious reasons!
  124.  
  125.   A very fast CPU and GFX Board is STRONGLY recommended.
  126.  
  127.   To fully enjoy PowerIcons you're suggested to use DefIcons and RAWBInfo
  128.   (even if not required): how to live without them ? ;-)
  129.  
  130.   Oh, you need some nice PNG icons too, of course! (However, I included
  131.   some nice examples made by me in the ExampleIcons drawer)
  132.  
  133.  
  134.  NOTE ABOUT SPEED
  135.  ----------------
  136.  
  137.   PowerIcons is intended for VERY fast and modern Amigas.
  138.   Even if loading of PNG icons is done 80% by hand (i.e. without the overhead
  139.   of libpng or -even worse!- datatypes system) this job will surely result
  140.   in much more stress for the CPU than loading plain Amiga icons.
  141.   Also, alpha-transparency blitting is done "by hand" since there's no API
  142.   for hardware alpha acceleration at the moment (I wrote highly optimized
  143.   routines but they cannot make miracles...)
  144.   So the fastest CPU and the fastest GFX card you have will never be too much.
  145.  
  146.   Best performance is obtained using PowerIcons 68K under Amithlon/UAE JIT or
  147.   PowerIcons PPC (with Amiga Workbench) under MorphOS.
  148.  
  149.  
  150.  NOTE ABOUT MORPHOS VERSION
  151.  --------------------------
  152.  
  153.   A very fast PowerPC version of PowerIcons is included for exclusive usage
  154.   under MorphOS. Actually, the only people who may benefit from this version
  155.   are Workbench users under MorphOS emulation (typically MorphOS 0.4 for
  156.   Amiga PowerUP). DON'T try to launch the included PPC version (PowerIcons.elf)
  157.   if you don't have MorphOS: your system will crash.
  158.  
  159.  
  160.  INSTALLATION
  161.  ------------
  162.  
  163.   Please remove ANY patches to icon.library, like my Ghosty (for example),
  164.   otherwise serious conflicts may take place !!!
  165.  
  166.   Copy PowerIcons executable in C: or wherever you want.
  167.  
  168.   PowerIcons should be launched in your Startup-Sequence with RUN (it doesn't
  169.   detach itself) JUST BEFORE LoadWB.
  170.   A typical line would look like:
  171.  
  172.    ...
  173.    Run >NIL: PowerIcons >NIL: [options]
  174.    LoadWB
  175.    EndCLI >NIL:
  176.  
  177.   On some slow machine *might* happen that desktop icons aren't patched by
  178.   PowerIcons. It never happened AFAIK, but if it's the case, a "wait 1" between
  179.   PowerIcons and LoadWB lines may help.
  180.  
  181.   Nothing prevents you from launching it by hand after Workbench has
  182.   started, but by doing so you won't be able to use PNG icons on the desktop
  183.   or in other applications (like AmiDock) started BEFORE PowerIcons!
  184.  
  185.   When you're sure you like PowerIcons and you plan to have it running definitely
  186.   on your machine, go in Workbench Prefs editor and set IconQuality to BAD. Since
  187.   color icons will be now drawn with true color remapping, doing so won't affect
  188.   icon quality (except when dragging icons from Workbench but that's practically
  189.   unnoticeable) and more pens will be available to your system.
  190.  
  191.  
  192.  USAGE
  193.  -----
  194.  
  195.   PowerIcons needs no icon and is intended mainly for command line usage.
  196.  
  197.   If you launch PowerIcons with a '?' as argument, a brief list of supported
  198.   options will be issued.
  199.  
  200.   PowerIcons supports the following options:
  201.  
  202.    GHOST=0...100     Transparency amount for default icons, i.e. for files
  203.                      without a "real" icon. A value of 100 means no transparency,
  204.                      50 means 50% background and 50% icon, and 0 means you won't
  205.                      see anything.
  206.                      Using a value of 100 will spedup things a bit since no
  207.                      additional computation for the transparency effect will be
  208.                      done.
  209.                      Suggested values range from 40 to 60. (Defaults to 40)
  210.  
  211.    NOGHOSTSELECT     Don't apply the transparency effect to default icons when
  212.                      they're selected. (Default is ghosting selected icons too)
  213.  
  214.    SWAPTEXTCOLORS    Use icon text color for background/outline/shade and background
  215.                      icon text color for the text. (Default is off)
  216.  
  217.    BETTEROUTLINE     With TEXTMODE=1 (outline) use eight instances of dark underlying
  218.                      text instead of only four, resulting in a more precise outline
  219.                      effect, mainly when using tiny fonts. Remember that this
  220.                      could slow down icon drawing and scrolling expecially on slow
  221.                      machines. (Default is off)
  222.  
  223.    SCROLLSPEEDUP     Enable a special trick to speed up icon scrolling in Workbench
  224.                      windows, restricting refresh only to those icons which really
  225.                      need being updated. Thanks to a suggestion from Georg Steger.
  226.                      (Default is off)
  227.  
  228.    TEXTMODE=(0|1|2)  Optionally, PowerIcons allows you to improve icon text
  229.                      rendering with shadow or outline effect. With 0, no effect
  230.                      will be applied and icon text will be rendered the same
  231.                      way your Workbench would do. With 1 you will get a nice
  232.                      outline effect and with 2 a shadow effect.
  233.                      The colors used for icon text and shadow/outline are those
  234.                      you set up in the Font prefs editor (but if you're using
  235.                      the SWAPTEXTCOLORS options they will be inverted, see above).
  236.                      (Defaults to 0)
  237.  
  238.    SELR=0...255
  239.    SELG=0...255
  240.    SELB=0...255      Red, Green and Blue values to add for PNG icons selection
  241.                      effect. Note that the PNG icon format used doesn't
  242.                      support an alternate image, so the selection effect can
  243.                      be obtained adding an RGB value to the icon image on the fly.
  244.                      Future versions of PowerIcons might support other effects
  245.                      like negative, darkening, RGB shift and so on.
  246.                      (Defaults to 96,96,144 which is a bluish lightening)
  247.  
  248.   For example:
  249.  
  250.    Run >NIL: PowerIcons NOGHOSTSELECT GHOST=50 SELR=80 SELG=80 SELB=80 TEXTMODE=1
  251.  
  252.  
  253.  REMOVING POWERICONS - WARNING!
  254.  ------------------------------
  255.  
  256.   To remove PowerIcons just launch it a second time.
  257.   Removing PowerIcons while PNG icons are still loaded by Workbench or by other
  258.   apps can be DANGEROUS! Please DON'T remove PowerIcons if you don't know
  259.   what you're doing.
  260.  
  261.  
  262.  LIVING WITH POWERICONS
  263.  ----------------------
  264.  
  265.   Firstly you should obtain some nice PNG icon pack to start enjoying
  266.   (and testing!) PowerIcons. Here are a few sources you may have a look at:
  267.  
  268.    -Aminet (there are some PNG icon archives on Aminet in pix/icon)
  269.    -www.kdelook.org (you will find a lot of PNG icon archives there)
  270.  
  271.   Once installed and launched correctly, PowerIcons adds transparent support
  272.   for PNG icons to the standard icon.library API. This means that you will be
  273.   able to fully handle PNG icons just as if they were standard Amiga icons.
  274.   Any program and utility using the icon.library API to copy, clone, draw and
  275.   delete icons will work flawlessly. Thus you will be able to use RAWBInfo (or
  276.   even the old, ugly Workbench Information requester) to easily change icon images
  277.   as usual, without dirtying your hands from a shell: you may drop a PNG icon over
  278.   a standard Amiga icon, a PNG icon over another PNG icon or even a standard Amiga
  279.   icon over a PNG one in RAWBInfo to change your icon image! If you (as suggested)
  280.   are using DefIcons, you will enjoy using PNG icons as default icons in ENVARC:Sys.
  281.   PNG AppIcons will work as well, and you can also drag your PNG icons into programs
  282.   like AmiDock...
  283.   In general, the only programs that won't work or that will work badly (or,
  284.   even, that might cause crashes with PowerIcons) are very old or very badly
  285.   written ones, which don't use the icon.library API to handle icons but rather
  286.   do too many things "by hand"...
  287.  
  288.  
  289.  HOW TO CREATE CUSTOM PNG ICONS OR PNG ICONS FROM PNG PICTURES ?
  290.  ---------------------------------------------------------------
  291.  
  292.   Simply rename your PNG image from Foo.png to Foo.info: your Workbench will be
  293.   ready to display and handle it as a normal icon!
  294.  
  295.   If you plan to draw your own PNG icons remember that creating good-looking
  296.   pictures with alpha channel is not really a child's play...
  297.   You need some practice, patience and some artistic talent.
  298.   ImageFX requires you know exactly what you're doing but is a good start point.
  299.  
  300.  
  301.  ABOUT PNG ICON FORMAT
  302.  ---------------------
  303.  
  304.   I don't know whether any standard has been set up or not for PNG icons over
  305.   the major platforms. The format I choose is the one adopted by Ambient, so
  306.   here I will mainly refer to it.
  307.  
  308.   PNG is a modern image file format supporting an often very high, lossless
  309.   compression and optional alpha-channel for gradual transparency.
  310.   PNG, just like IFF, supports different Hunks to store additional information
  311.   like (in our case) an "icon" Hunk containing icon data (eg. drawer position,
  312.   tooltypes, stack size, default tool, etc.)
  313.  
  314.   PNG icons are nothing else than normal PNG pictures whose name ends up with
  315.   ".info", with (or without, when just created) a special "icon" Hunk to keep
  316.   the proper icon information.
  317.  
  318.   If you're not familiar with alpha channel, it's simply an additional byte for
  319.   every pixel specifying to what extent the image will be mixed with background.
  320.   Typically, like in the case of the supported PNG format, images will use 32
  321.   bits per pixel: 1 byte for each red, green and blue as usual plus an additional
  322.   byte for transparency (the alpha channel value).
  323.  
  324.   A pixel containing an alpha value of zero will look as the corresponding
  325.   background pixel (0% picture, 100% bg). A pixel with an alpha value of 128
  326.   will be displayed as (about) the average of that pixel and the corresponding
  327.   background pixel (50% picture, 50% bg), while an alpha value of 255 will show
  328.   exactly the corresponding pixel with no background (100% picture, 0% bg).
  329.   As you can see, alpha channel offers more complex transparency capabilities
  330.   than the ugly-looking 0/1 masking we are used to, for example, with standard
  331.   Amiga icons. Antialiased borders, lighting effects as well as shadows are now
  332.   possibile with a properly drawn 32-bit image.
  333.  
  334.   PNG icons have NO intrinsic type, i.e. there's no field defined to establish
  335.   whether an icon is of type Drawer rather than Tool or Disk...
  336.   The new icon.library engine added by PowerIcons automatically adapts the
  337.   loaded (or default) icon to the corresponding file, setting the correct
  338.   type on the fly so that Workbench may properly understand and use it.
  339.   The only identifying rule is represented by the fields containing Drawer
  340.   Data or DefaultTool. If an icon contains a DefaultTool, it will be early
  341.   identified as a project (if that causes no inconsistency). If an icon
  342.   contains some DrawerData, it will (possibly) be suitable as a drawer or disk
  343.   icon.
  344.  
  345.   At PNG level, you can then have "virgin" icons, i.e. PNG images not containing
  346.   any "icon" hunk yet (mainly, this happens when an icon has just been created
  347.   from a paint program and/or hasn't been snapshotted or modified yet) but you
  348.   won't absolutely need to care about it.
  349.  
  350.   When you first snapshot an icon, or create its Tooltypes, DefaultTool,
  351.   StackSize and/or other icon information, an "icon" hunk is automatically
  352.   created to hold the needed information in the PNG icon file.
  353.  
  354.  
  355.  KNOWN LIMITATIONS
  356.  -----------------
  357.  
  358.   No. NO. NOOO!!!!! PowerIcons DOESN'T WORK WITH MAGELLAN OR SCALOS!!!!!!!!!!
  359.   These desktops do every icon operation by hand without using the icon.library
  360.   API so there's definitely NO WAY! Don't ask it anymore !
  361.  
  362.   Since Workbench uses internal planar routines for icon dragging, it wasn't
  363.   possible to have it dragging true color imagery. A simple four-color image
  364.   representing a white box with an arrow has been provided just to have Workbench
  365.   displaying something when dragging PNG icons. Unfortunately there's definitely
  366.   NO OTHER SOLUTION. Please DON'T ask to improve it.
  367.  
  368.   For obvious reasons you won't be able to use standard icon editors on PNG
  369.   icons. Please don't, since you may obtain unpredictable results, and really
  370.   there's no need.
  371.  
  372.   Compatibility with other system or icon.library patches CANNOT BE GUARANTEED!
  373.  
  374.   Compatibility with utilities to inject or change icon imagery is absolutely
  375.   not guaranteed (99% of them won't work or will destroy any previously stored
  376.   PNG imagery).
  377.  
  378.   Ghosting of icon text (like in Ghosty indeed) is not implemented yet, by
  379.   choice, in order to reduce the overhead, and for many other technical reasons.
  380.  
  381.   Old-style amiga icons (planar icons) are simply NOT patched by choice.
  382.   No true-color remapping or ghost effect is applied in the case such an ugly
  383.   old icon is encountered and it will be passed to the original DrawIconState()
  384.   as it is.
  385.  
  386.   Icon border is NOT supported by choice.
  387.  
  388.   For speed reasons, not all PNG image formats are supported. Please use only
  389.   True Color pictures with or without alpha channel (24 or 32 bits). Grayscale,
  390.   palette mapped, interlaced, not-alpha transparency pictures and many other
  391.   exotic formats are NOT supported.
  392.  
  393.  
  394.  A FINAL NOTE...
  395.  --------------------
  396.  
  397.   You will probably start loving and using PowerIcons from the beginning. So
  398.   you'll spend hours and hours drawing 32 bit icons or customizing your programs
  399.   with shiny icons downloaded from somewhere.
  400.   But remember: at that point there's NO WAY TO SWITCH BACK! If you (for
  401.   any reason) should remove PowerIcons you WON'T BE ABLE TO SEE YOUR ICONS AND
  402.   YOUR TOOLTYPES ANYMORE!
  403.  
  404.   What does that mean ? Nothing particular, that's quite obvious indeed.
  405.   You're just warned :)
  406.  
  407.  
  408.  ******************************************************************************
  409.  
  410.                         ! ENJOY AND LOVE POWERICONS !
  411.  
  412.                    ! PLEASE SEND ME ANY BUG OR SUGGESTION !
  413.  
  414.  ******************************************************************************
  415.  
  416.  AUTHOR:
  417.  
  418.   Elena Novaretti
  419.   www.elena-fractals.it
  420.   <uni-dea@jumpy.it>
  421.  
  422.  
  423.  PowerIcons has been developed on a Pegasos(tm) and compiled with the great VBCC.
  424.  
  425.